



NDP (PSG Driver for MSX) / #MSXNDP          Programmed by naruto2413
--------------------------------------------------------------------
version 1.05                                                基本説明




この度はPSGドライバ「NDP」に興味をお持ちいただきまして、誠にありがとうございます。

このアーカイブはMSX用のPSGドライバ本体と、Windows用のエディタおよびMMLコンパイラで構成されています。




▼動作条件

【ドライバ本体】
MSX (NTSC 60Hz) / RAM64KB
※PAL 50Hzでも動作しますが、BPMは遅くなります。

【エディタおよびMMLコンパイラ】
Windows7/8/10/11(x86/x64) + .NET Framework 4.8
※ARM環境は動作保証外です（動かなかった報告、動いた報告ともに頂いています）。




▼エディタ起動方法

動作条件を満たしたWindows環境にて、ndp.exeを実行してください。




▼最低限のチュートリアル

1) ndp.exeを起動（初回起動時は次項「音質調整」を参考に再生音質を調整）
2) MMLエディタ上で 1 cde のようにMMLを入力
3) F5キーを押すと演奏開始（再生ボタンの表示が白抜きの時は一時停止の続きから再生）
4) Escキー（またはF3キー）を押すと停止、または一時停止（もう一度押すと演奏停止）※メニューで変更可能
5) Shift+F5キーでカーソル位置から再生、Ctrl+F5キーでカーソル位置からソロ再生なども可能
6) 曲が仕上がったら用途に合わせてNDPファイル、KSSファイル、WAVファイルなどを保存

※具体的な書式やMMLコマンドなどは、docsフォルダ内の「2_MML書式.txt」、またはhelpフォルダ内の「help.html」をご参照ください。

※各機能を使用した簡単なサンプルMMLがsampleフォルダに入っていますので、合わせてご参照ください。




▼WAVファイルについて

現状、[ファイル]→[名前を付けてWAVファイルを保存]で出力できるファイルは44.1kHz/16ビット/ステレオ固定です。
無限ループの曲は2ループ半ほどの長さで出力されます。




▼KSSファイルについて

　KSSファイルは、ドライバや曲データを内包したメモリ空間のイメージが収められているファイルです。
　CPUや各種音源のI/Oなども定められており、プレイヤー側のエミュレーションで曲データを再生できます。

　Digital Sound Antiquesさんの「M3disp」( https://m3.ym2413.com/ ) で環境を問わずにWebブラウザ上で再生可能です。
　M3dispのウェブサイトを開き、KSSファイルをドラッグ＆ドロップしてください。

　また、Windows用のKSS対応プレイヤーとしてkobarinさんの「KbMedia Player」( https://kobarin.sakura.ne.jp/ ) もあり、
　MSXplugのKbMedia Player版が同梱されていますので、準備不要でKSSファイルを再生できます。




◆一括コンパイル／プレイリスト作成

　複数のMMLファイルをエディタにドロップすると、一括コンパイルを行うことができます。
　（[出力]→[一括コンパイル / ファイル出力] のメニューからも実行できます）

　さらに、KSSファイル出力時には再生時間なども含むプレイリスト（m3uファイル）を出力可能です。
　エンコーディングなども選択できますので、お使いのプレイヤーに合わせてご設定ください。




▼音質調整

再生にはDigital Sound Antiquesさんの「MSXplug」を使用しているため、音量や音質もMSXplug側の設定に依存します。

1) MMLエディタのメニューから、[表示]→[MSxplugのダイアログを開く]
2) MSXplugのファイル情報ダイアログのメニューから、[表示]→[詳細設定]
3) [マスター] タブでメインの音量を設定
4) [フィルタ] タブで各フィルタを設定（音のこもり具合などの調整）
5) [デバイス] タブでPSGのチップ種別を選択（AY-3-8910は初期のMSX1相当、YM2149は中期以降のMSX2/2+/turboR相当）




▼MMLのシンタックスハイライト（色分け）について

xshd フォルダにある *.xshd ファイルで定義されています。

mml          .xshd --- ダークモード（通常時）
mmllight     .xshd --- ライトモード（〃）

mml_note     .xshd --- ダークモード（表示メニューの「MMLのノート情報以外を薄い色にする」有効時）
mmllight_note.xshd --- ライトモード（〃）

ruleset      .xshd --- 共通ルールセット

これらのファイルをテキストエディタで直接編集し、[表示]→[MMLの色分け表示]をOFF→ON、
またはnpd.exeを再起動すると適用されます。

シンタックスハイライト自体が不要な場合は、表示メニューからオフにしてください。




▼ボイスエディタについて

[表示]→[ボイスエディタを表示]、またはMMLエディタ上でAlt+1キーを押すと立ち上がります。

1フレームずつ遷移するソフトエンベロープを視覚的に作成できます。

アプリ起動直後はプリセット音色があらかじめ登録されています。
1から作成する場合は、表示中の音色データを右下のごみ箱ボタンで消去してください。

エディタ上の音色はそのままMMLエディタ上で鳴らすことができますが、
「@<値>=」で始まる色定義用のMMLを曲データ内にコピー＆ペーストしておくと明示的に設定できます。

また、音色定義用のMMLを直接入力してEnterキーを押すと、その内容がエディタに反映されます。
@で指定されている音色番号は無視され、エディタ上の番号で定義されますので、コピーなどに便利です。

さらに下段のテキストボックスは音色試聴用のMML入力エリアです。
このMMLを書き換えると、任意の内容で試聴できます。


・ボイスエディタの操作方法

　[マウス移動]
　マウスポインタ移動

　[左クリック]
　該当フレームの音量を設定

　[右クリック]
　終端指定 (この音量を最後に維持する)

　[右ドラッグ]
　ループ指定 (指定範囲のエンベロープを無限ループ。トレモロなどに有用)

　[F5キー]
　音色試聴 (ウィンドウ下部の編集可能テキストボックス内に書かれたMMLを再生)

　[F3キー/Escキー]
　音色試聴停止

　[Ctrl+上下キー]
　音色選択

　[Ctrl+Sキー]
　音色データを保存

　[Ctrl+Oキー]
　音色データを開く




▼リズムボイスエディタについて

[表示]→[リズムボイスエディタを表示]、またはMMLエディタ上でAlt+2キーを押すと立ち上がります。

1列1フレーム分の指定となっており、各パラメータの遷移を記述していくタイプのエディタです。
最初に音量やハードエンベロープを指定しないと無音になる点にご注意ください。
また、ハードエンベロープと音量は同時に設定できません（PSG自体の仕様）。

ボイスエディタ上の音色はそのままMMLエディタ上で鳴らすことができますが、
「@R:<音名>=」で始まる音色定義用のMMLを曲データ内にコピー＆ペーストしておけば明示的に設定できます。

また、音色定義用のMMLを直接入力してEnterキーを押すと、その内容がエディタに反映されます。
@Rで指定されている音色名は無視され、エディタ上の音色名で定義されますので、コピーなどに便利です。

さらに下段のテキストボックスは音色試聴用のMML入力エリアです。
このMMLを書き換えると、任意の内容で試聴できます。


・リズムボイスエディタの操作方法

　[マウス移動+クリック / カーソルキー]
　入力エリア選択

　[数字キー / 左クリック / スペースキー]
　数値入力、チェックON/OFF

　[F5キー]
　音色試聴 (ウィンドウ下部の編集可能テキストボックス内に書かれたMMLを再生)

　[F3キー/Escキー]
　音色試聴停止

　[Ctrl+上下キー]
　音色選択

　[Ctrl+Sキー]
　リズム音色データを保存

　[Ctrl+Oキー]
　リズム音色データを開く




▼MSX-BASIC上で曲データを鳴らす場合

あらかじめ、曲データをBSAVE形式で保存しておきます。
（MMLエディタ上で[ファイル(F)]→[名前を付けてBSAVE形式で保存(B)]）

以下、MSX-BASIC上でB000Hから曲データを配置して鳴らす手順です。
C000Hからドライバ本体が配置されますので、この例の場合、曲データは最大4KB(B000H～BFFFH)に収める必要があります。

※これらのアドレスは現時点のものであり、今後の更新で変更される可能性がありますのでご注意ください。

1) CLEAR文で曲データとドライバのメモリを確保しておきます。

	> CLEAR 200,&HB000

2) BLOAD文でドライバ本体をロードして、初期化ルーチン（タイマ割り込みフックにドライバ接続）を実行します。

	> BLOAD "NDP.BIN",R

3) DEFUSR文で演奏開始・停止・曲データアドレス設定・一時ミュートなどのエントリを定義します。

	> DEFUSR0=&HC003 '演奏開始
	> DEFUSR1=&HC006 '演奏停止
	> DEFUSR2=&HC00C '曲データアドレス設定
	> DEFUSR3=&HC00F 'PSG Ch.A 一時ミュート (フレーム数をUSR文の引数で指定 [1=解除/255=常時ミュート])
	> DEFUSR4=&HC012 'PSG Ch.B 〃
	> DEFUSR5=&HC015 'PSG Ch.C 〃
	> DEFUSR6=&HC018 'マスター音量 (下げる音量をUSR文の引数で指定 [0～15])
	> DEFUSR7=&HC01B 'フェードアウト (フレーム数をUSR文の引数で指定 [1～255])
	> DEFUSR8=&HC01E 'フェードインしながら演奏開始 (フレーム数をUSR文の引数で指定 [1～255])
	> DEFUSR9=&HC04B 'ドライバ終了（割り込みフックからドライバを切り離して発音停止）

4) BLOAD文で曲データのアドレスを指定してロードします。

	> BLOAD "BGM1.NDP",&HB000

5) USR文で曲データのアドレスを設定します。

	> U=USR2(&HB000)

6) USR文で演奏開始および停止を実行します。

	> U=USR0(0) '演奏開始
	> U=USR1(0) '演奏停止

	※ U=USR(0) のかわりに U=USR8(20) のようにするとフェードインしながら演奏開始できます。

7) 演奏中、チャンネル単位で一時ミュートできます。自作プログラムで効果音を鳴らす際に有用です。
   ミュートするフレーム数（2～254）を引数で指定してください。255で常時ミュートです。
   また、1でレジスタを復帰せずに即ミュート解除となります。通常は2以上を指定してください。

	> U=USR3(60) 'PSG Ch.Aを60フレーム（約1秒）ミュート
	> U=USR4(10) 'PSG Ch.Bを10フレームミュート

8) 演奏中、マスター音量を操作したり、フェードアウトさせることもできます。

	> U=USR6(3) 'マスター音量を3下げる（0で最大、15で最小）
	> U=USR7(30) '1段階あたり30フレームかけてフェードアウト

9) 効果音は、DEFUSR文の効果音用エントリ（&HC021）で引数に効果音データのアドレスを指定すると発音できます。

	> DEFUSR2=&HC00C : U=USR2(&HD600)

10) 終了時は、ドライバ終了ルーチン（タイマ割り込みフックからドライバ切り離し）を実行してください。


・サンプルプログラム

10 CLEAR 200,&H9000:DEFINT A-Z:SCREEN 0:KEY OFF
20 DEFUSR=&HC003:DEFUSR1=&HC006:DEFUSR2=&HC00C
30 DEFUSR3=&HC00F:DEFUSR4=&HC012:DEFUSR5=&HC015:DEFUSR6=&HC018:DEFUSR7=&HC01B:DEFUSR8=&HC04B
40 BLOAD"NDP.BIN",R:PRINT"LOAD & INITIALIZE NDP"
50 BLOAD"BGM1.NDP",&H9000:PRINT"LOAD BGM"
60 U=USR2(&H9000)'BGM ADDRESS SET
70 PRINT:PRINT "    0 : BGM PLAY"
80 PRINT "    1 : Ch.A MUTE (1sec)"
90 PRINT "    2 : Ch.B MUTE (2sec)"
100 PRINT "    3 : Ch.C MUTE & SE"
110 PRINT " 4-15 : MASTER VOLUME (V4-15)"
120 PRINT "16-95 : FADE OUT (1-80frame)"
130 PRINT "   99 : BGM STOP & END"
140 LOCATE 0,11:PRINT "     ":LOCATE 0,11:INPUT A
150 IF A=0 THEN U=USR(0)
160 IF A=1 THEN U=USR3(60)
170 IF A=2 THEN U=USR4(120)
180 IF A=3 THEN U=USR5(25):PLAY"","","T180O6L16V15F+DV13F+D"
190 IF A>3 AND A<16 THEN U=USR6(15-A)
200 IF A>15 AND A<96 THEN U=USR7(A-15)
210 IF A=99 THEN 900
220 GOTO 140
900 U=USR1(0)'BGM STOP
910 U=USR8(0)'DRIVER OFF
920 END




▼マシン語で曲データを鳴らす場合

1) C000Hからドライバをロード
2) NDPINI（ドライバ初期化）を実行 ※タイマ割り込みにドライバが接続される
3) 任意のアドレスに曲データをロード
4) ADRSET（曲データ開始アドレス設定）で曲データのアドレスを指定
5) MSTARTで再生、MSTOPで停止など各エントリで操作
6) NDPOFFでドライバ終了 ※タイマ割り込みからドライバが切り離される

各エントリについての詳細は、「3_ドライバ仕様.txt」をご参照ください。




▼効果音について

MMLで「!S」コマンドにより最大99個まで定義でき、曲データから鳴らすことも、自作プログラムから鳴らすこともできます。


【注意】

・音色、ピッチエンベロープ（ビブラート）、ノートエンベロープは曲データと効果音データで共用となります。
　（これらをまとめたバイナリデータのことをNDPでは「音色定義データ」と呼ぶことにしています）
　そのため、効果音の再生前にあらかじめ曲データを再生しておくか、マシン語用のVSETエントリを使用して
　ドライバのワークエリアに音色定義データを反映させておくようにしてください。

　※ダミーの曲データを用意したり、任意のアドレスに音色定義データを配置する機能を活用するなど、方法は問いません。
　　効果音では@15の音色を使うことにしておき、最初にダミーの曲データで@15を定義しておくのが手軽です。

・効果音よりもリズムトラックが常に優先されますので、リズムの割り込まれるトラック（デフォルトではトラック3）を
　効果音で使用する際は、リズムが発音されていない状況（休符またはトラック未使用）になっている必要があります。

・効果音データの中では@Cコマンド、@RMコマンド、リズムトラックは使用できません。

・#ADDRESS-SEヘッダを設定して効果音ファイルを出力した場合、各効果音のアドレスはログよびアセンブリソース内の
　コメントとして出力されます。
　アドレスは4000H以降、かつ曲データやドライバの領域と被らないようにご注意ください。

・#ADDRESS-SEヘッダを設定せずに効果音ファイルを出力した場合、ファイルの先頭に効果音の個数（1バイト）と
　各効果音の相対アドレステーブル（2バイト×個数）を出力します。
　外部プログラムから効果音を鳴らす際は効果音データのアドレスが必要となりますので、適宜ご活用ください。


以下、自作プログラムから効果音を鳴らすための手順です。

1) MMLエディタ上で、効果音で使う音色データを含む無音の曲データをダミーで作成しておきます。

	[例]
	@15=F
	123 @15

2) MMLエディタ上で「!S」コマンドにより、効果音を作成します。
   （曲データの内容は問わないので、効果音を試聴できるようにしておくと便利）

	[例]
	;効果音配置アドレスを設定
	#ADDRESS-SE  0D600H

	;効果音で使う音色データ
	@15=F

	;効果音試聴用MML
	1 !S1 r4  ;効果音1番を試聴
	1 !S2 r4  ;効果音2番を試聴

	;効果音定義
	!S1  ;効果音1番に次のMMLを定義
	2 @15 v15 *1 o5c_>c32
	!S2  ;効果音2番に次のMMLを定義
	3 @15 v15 *1 o4c_<c24

3) [ファイル]→[名前を付けて効果音データをBSAVE形式とDB形式で保存] を実行し、効果音データを保存します。

4) 保存された効果音データのASMファイルをテキストエディタ等で開き、定義した効果音のアドレスを確認します。

	[例]
	ORG	0D600H

	SE1:	;0D600H
	DB	8,0,9,0,20,0,0,0,255,96,129,1,112,161,0,36,49,61,3,255,255

	SE2:	;0D615H
	DB	8,0,9,0,10,0,0,0,255,255,96,129,1,112,161,0,86,37,25,5,255

	※この例の場合、効果音1番はD600Hから、効果音2番はD615Hから配置されています。
	（#ADDRESS-SEヘッダを使用しないと相対アドレスになります）

5) MSX上でドライバをロードして初期化します。

6) 効果音で使う音色などを含む曲データ（1で作ったもの）を再生しておきます。
   （音色やエンベロープのアドレスをドライバのワークエリアに反映させておくため）

7) メモリ上に効果音データを配置し、効果音発音エントリを実行します。

	[例] BASICの場合
	DEFUSR=&HC021:U=USR(&HD600)

	[例] マシン語の場合
	SEPLAY  EQU  0C042H
	        LD   DE,0D600H
	        CALL SEPLAY




【driverフォルダのファイル構成】

　NDP    .ASM - 下記2ファイルをインクルードしてアセンブルするためのファイル
　NDP_DRV.ASM - ドライバ本体
　NDP_WRK.ASM - コールエントリ／ワークエリア／テーブル
　NDP    .BIN - 通常の方法でアセンブルしたドライバ

　ドライバ本体は自己書換などはしていませんので、ROMにも置けます。
　ワークエリアは原則としてページ3のRAMに配置してください。
　詳しくは 3_ドライバ仕様.txt の「ROM化などにあたっての諸注意」をご参照ください。




